QuickTime Streaming

Sample Processing Functions

Once setup is complete, QuickTime will begin calling your packetizer's RTPMPSetSampleData function. This is where most of a typical packetizer's work is done. Your packetizer is presented with a block of media sample data, you break it into packets according to your own algorithm, and you pass the results to the selected packet builder. If your packetizer works synchronously, you packetize the data and return 0 in outFlags . If you need more sample data to complete a packet, return kRTPMPWantsMoreDataFlag .

If your packetizer works asynchronously, you set outFlags to kRTPMPStillProcessingData and your packetizer continues its work in the RTPMPIdle function, which will be called periodically. RTPMPIdle should also set outFlags to kRTPMPStillProcessingData if it still has work to do. It sets outFlags to 0 if all the sample data has been processed.

If your packetizer works synchronously, RTPMPIdle always sets outFlags to 0 .

Note that the caller owns the RTPMPSampleDataParams struct. Your media packetizer must copy any fields of the struct it wants to keep. The caller will maintain only the media data in the struct until you call the release proc.

Your media packetizer must call the release proc when done with the media data.

Do the processing work in the RTPMPSetSampleData function if it does not take up too much CPU time; otherwise, do it in your idle function.



 
pascal ComponentResult RTPMPSetSampleData(RTPMediaPacketizer rtpm,

                const RTPMPSampleDataParams *inSampleData, SInt32 *outFlags);



 
/* flags for RTPMPSampleDataParams*/

enum {

    kRTPMPSyncSampleFlag= 0x00000001

};      

struct RTPMPSampleDataParams {

    UInt32                  version;

    UInt32                  timeStamp;

    UInt32                  duration;           /* 0 if not specified*/

    UInt32                  playOffset;         /* 0 if not specified*/

    Fixed                   playRate;

    SInt32                  flags;

    UInt32                  sampleDescSeed;

    Handle                  sampleDescription;

    RTPMPSampleRef          sampleRef;

    UInt32                  dataLength;

    const UInt8 *           data;

    RTPMPDataReleaseUPP     releaseProc;

    void *                  refCon;

};



 
typedef struct RTPMPSampleDataParamsRTPMPSampleDataParams;

version: Version of the data structure. Currently always 0.
timeStamp: RTP time stamp for the presentation of the sample data. This time stamp has already been adjusted by edits, edit rates, etc.
duration: Duration (in RTP time scale) of the sample.
playOffset: Offset within the media sample itself. This is only used for media formats where a single media sample can span across multiple time units. QuickTime Music is an example of this, where a single sample spans the entire track. For most video and audio formats, this will be 0.
playRate: 1.0 (0x00010000) is normal. Higher numbers indicate faster play rates. Note that timeStamp is already adjusted by the rate. This field is generally of interest only to audio packetizers.
flags: kRTPMPSyncSampleFlag is set if the sample is a sync sample (key frame).
sampleDescSeed: If the sample description changes, this number will change.
sampleDescription: The sample description for the given media sample
sampleRef: Private field.
dataLength: Size of media data
data: Pointer to media data
releaseProc: If set, you need to call it when you are finished with the sample data.
refCon: Pass to releaseProc
outFlags: Set to kRTPMPStillProcessingData if you are not done with the sample. This will cause your idle routine to be called.

If you can't do all the processing of the sample data in response to the RTPMPSetSampleData function, sets outFlags to kRTPMPStillProcessingData and do the work in your RTPMPIdle function:



 
// do work here if you need to - give up time periodically

// if you're doing time consuming operations

pascal ComponentResult RTPMPIdle(RTPMediaPacketizer rtpm,

                SInt32 inFlags, SInt32 *outFlags);

This call is made periodically if you sets outFlags to kRTPMPStillProcessingData in your RTPMPSetSampleData routine. If you need more time, sets outFlags to kRTPMPStillProcessingData in RTPMPIdle as well. This will cause RTPMPIdle to be called again. When you are finished packetizing the sample data you were passed in the last RTPMPSetSampleData call, sets outFlags to 0 .

If you do work in the RTPMPIdle function, the idle function needs to call the release proc when you are done with the sample data.